<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>StrPut / StrGet</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>StrPut() / StrGet() <span class="ver">[AHK_L 46+]</span></h1>

<p>Copies a string to or from a memory address, optionally converting to or from a given code page.</p>

<pre class="Syntax">StrPut(String [, Encoding = <i>None</i> ] )
StrPut(String, Address [, Length] [, Encoding = <i>None</i> ] )
StrGet(Address [, Length] [, Encoding = <i>None</i> ] )</pre>
<h3>Parameters</h3>
<dl>

  <dt>String</dt>
  <dd><p>Any string. Numbers are also acceptable.</p></dd>

  <dt>Address</dt>
  <dd><p>The address at which the string will be written to/read from.</p></dd>

  <dt>Length</dt>
  <dd><p>The maximum number of characters to read/write, including the null-terminator if required.  See Return Value.</p></dd>

  <dt>Encoding</dt>
  <dd><p>The source encoding for StrGet or target encoding for StrPut; for example, "UTF-8", "UTF-16" or "CP936".  If <em>Address</em> and <em>Length</em> are not specified, numeric identifiers must be prefixed with "CP".  Specify an empty string or "CP0" to use the system default ANSI code page.</p></dd>

</dl>

<h3>Return Value</h3>
<p>For either function, invalid parameters cause an empty string to be returned.</p>
<p>StrPut returns the number of characters written, the required buffer size in characters if no <i>Address</i> was given, or 0 if an error occurred.  If <em>Length</em> is less than the length of the source string, the function fails and returns 0.  If <em>Length</em> is exactly the length of the source string, the string is not null-terminated; otherwise the returned count includes the null-terminator.</p>
<p>StrGet returns the requested string after performing any necessary conversion.</p>

<h3>Remarks</h3>
<p>Note that the <i>String</i> parameter of StrPut and return value of StrGet are always in the <a href="../Compat.htm#Format">native encoding</a> of the current executable, whereas <i>Encoding</i> specifies the encoding of the string written to or read from the given <i>Address</i>. If no <em>Encoding</em> is specified, the string is simply measured or copied without any conversion taking place.</p>
<p>If conversion between code pages is necessary, the required buffer size may differ from the size of the source <em>String</em>.</p>
<p>Scripts which are required to be compatible with AutoHotkey Basic can still use StrPut and StrGet provided that <a href="http://www.autohotkey.com/forum/topic59738.html">the appropriate script files</a> are installed in a <a href="../Functions.htm#lib">function library</a>. These scripts can be found at the <a href="http://www.autohotkey.com/forum/">AutoHotkey Community Forum</a>.</p>

<h3>Related</h3>
<p><a href="../Compat.htm">Script Compatibility</a>, <a href="FileEncoding.htm">FileEncoding</a>, <a href="VarSetCapacity.htm">VarSetCapacity()</a></p>

<h3>Examples</h3>
<p>Either <em>Length</em> or <em>Encoding</em> may be specified directly after <em>Address</em>, but in those cases <em>Encoding</em> must be non-numeric:</p>
<pre class="NoIndent">strA := StrGet(addressA, "cp0")     <em>; OK</em>
strA := StrGet(addressA, length, 0) <em>; OK</em>
strA := StrGet(addressA, 0)         <em>; Error</em></pre>

<p>StrPut may be called once to calculate the required buffer size for a string in a particular encoding, then again to encode and write the string into the buffer.  If you frequently use variables with StrPut, consider adding this function to your <a href="../Functions.htm#lib">library</a>:</p>
<pre class="NoIndent">StrPutVar(string, ByRef var, encoding)
{
    <em>; Ensure capacity.</em>
    VarSetCapacity( var, StrPut(string, encoding)
        <em>; StrPut returns char count, but VarSetCapacity needs bytes.</em>
        * ((encoding="utf-16"||encoding="cp1200") ? 2 : 1) )
    <em>; Copy or convert the string.</em>
    return StrPut(string, &amp;var, encoding)
}</pre>

</body>
</html>
